Introduce seed in `random_color` method to produce colors deterministically #4265

ishu9bansal · 2025-06-04T09:42:38Z

Overview: What does this pull request change?

Introduces a new class RandomColorGenerator, which enables deterministic generation of colors from Manim's color palette using an optional seed.
Refactors the random_color() function to use this class internally, preserving existing behavior and output style.

Motivation and Explanation: Why and how do your changes improve the library?

The existing random_color() function uses Python’s global random module, which makes the results non-deterministic and unsuitable for use cases like tests or reproducible animations.

This PR introduces RandomColorGenerator, a utility that allows users to generate a repeatable sequence of random Manim colors by initializing it with a specific seed. The sequence is generated statefully—each call to .next() returns the next color in that seeded sequence. Here’s an example:

>>> from manim.utils.color.core import RandomColorGenerator
>>> rnd = RandomColorGenerator(42)
>>> rnd.next(), rnd.next()
(ManimColor('#ECE7E2'), ManimColor('#BBBBBB'))

>>> rnd2 = RandomColorGenerator(42)
>>> rnd2.next(), rnd2.next()
(ManimColor('#ECE7E2'), ManimColor('#BBBBBB'))  # same as above

Meanwhile, the random_color() function continues to behave the same:

>>> from manim import random_color
>>> random_color()
ManimColor('#9A72AC')

This ensures full backward compatibility, with zero impact on existing code using random_color().

Further Information and Comments

Based on the discussion in the related issue, this design addresses two key requirements:

Provide a deterministic way to generate random colors for testing or consistent rendering.
Do not introduce breaking changes to the existing random_color() API, which is widely used.

Importantly, we do not add a seed parameter to random_color() to avoid confusion around stateless vs stateful behavior. Instead, the RandomColorGenerator class provides an explicit, opt-in mechanism for seeded, stateful random color generation—making the intended behavior clear to users.

This separation keeps the API clean while offering more control to advanced users who need it.

Reviewer Checklist

The PR title is descriptive enough for the changelog, and the PR is labeled correctly
If applicable: newly added non-private functions and classes have a docstring including a short summary and a PARAMETERS section
If applicable: newly added functions and classes are tested

for more information, see https://pre-commit.ci

ishu9bansal · 2025-06-04T09:43:34Z

Referencing issue #1671

I’m open to further discussion to fine-tune the implementation. For example, we could consider using a singleton instance in the default (non-seeded) case instead of creating a new object each time.

If the overall approach looks good, I’m happy to iterate further and refine the PR for production readiness.

manim/utils/color/core.py

behackl

I think this is a nice proposal, and a good resolution for this over-due issue. This approach would still work (or at least, could be made to work) in case we ever decide to introduce a module-global seed (ManimConfig.random_seed ...).

Could you please:

double check that the line in the docstring, L1515 is not too long and break it if otherwise,
add a PARAMETERS-section to the class docstring where the seed argument of the initializer is documented,
and add the fixed-seed example from the description either as a unit test (together with the other color module tests) or as a doctest in an EXAMPLES section of the docstring? (I have a slight preference for the latter, as it simultaneously documents the usage of the generator class.)

Thank you for your contribution!

ishu9bansal · 2025-06-04T10:44:33Z

Great!
Let me make the changes you suggested. @behackl
Meanwhile, please assign this issue to me.

uwezi · 2025-06-04T10:45:55Z

May I add a little suggestion: I now often use np.random.choice() to get a random color from a given list of colors, since not all colors usually fit to the theme of a scene, particularly also if the background color is included in the draw.

Could you consider to add an additional, optional parameter to the __init__ which sets a list of colors instead of manim_colors._all_manim_colors?

One additional question: since numpy is already present in Manim, is there any reason to use random instead of numpy.random?

ishu9bansal · 2025-06-05T07:41:02Z

Could you consider to add an additional, optional parameter to the __init__ which sets a list of colors instead of manim_colors._all_manim_colors?

@uwezi
Sure, we can take the list of colors as the given pallet in init params, and default it to _all_manim_colors.
I can add this as well.

Update:
Done ✅

…ator

manim/utils/color/core.py

ishu9bansal · 2025-06-05T08:22:23Z

@behackl please review and suggest anything else that needs to be changed.

manim/utils/color/core.py

+    ) -> None:
+        self.choice = random.choice if seed is None else random.Random(seed).choice
+
+        from manim.utils.color.manim_colors import _all_manim_colors


behackl

Looks good! I've left a hand full of suggestions to improve how the docstrings are rendered, please take a look.

I'll also push one additional commit in a second to fix the rendering of the code snippets.

Other than that, this seems good to go for me. Let me know once you've checked my suggested changes!

behackl · 2025-06-07T09:59:27Z

manim/utils/color/core.py

+    """
+    A generator for producing random colors from a given list of Manim colors,


Suggested change

"""

A generator for producing random colors from a given list of Manim colors,

"""A generator for producing random colors from a given list of Manim colors,

behackl · 2025-06-07T09:59:44Z

manim/utils/color/core.py

+    optionally in a reproducible sequence using a seed value.
+
+    When initialized with a specific seed, this class produces a deterministic
+    sequence of `ManimColor` instances. If no seed is provided, the selection is


Suggested change

sequence of `ManimColor` instances. If no seed is provided, the selection is

sequence of :class:`.ManimColor` instances. If no seed is provided, the selection is

behackl · 2025-06-07T10:00:19Z

manim/utils/color/core.py

+
+    Parameters
+    ----------
+    seed : int | None, optional


type annoations are taken from the actual type hints, no need to add them twice

Suggested change

seed : int | None, optional

seed

behackl · 2025-06-07T10:00:30Z

manim/utils/color/core.py

+        A seed value to initialize the internal random number generator.
+        If None (default), colors are chosen using the global random state.
+
+    sample_colors : list[ManimColor], optional


Suggested change

sample_colors : list[ManimColor], optional

sample_colors

behackl · 2025-06-07T10:00:47Z

manim/utils/color/core.py

+    ----------
+    seed : int | None, optional
+        A seed value to initialize the internal random number generator.
+        If None (default), colors are chosen using the global random state.


Suggested change

If None (default), colors are chosen using the global random state.

If ``None`` (the default), colors are chosen using the global random state.

behackl · 2025-06-07T10:01:06Z

manim/utils/color/core.py

+        If None (default), colors are chosen using the global random state.
+
+    sample_colors : list[ManimColor], optional
+        A custom list of Manim colors to sample from. Defaults to the full Manim color palette.


Suggested change

A custom list of Manim colors to sample from. Defaults to the full Manim color palette.

A custom list of Manim colors to sample from. Defaults to the full Manim

color palette.

behackl · 2025-06-07T10:02:09Z

manim/utils/color/core.py

+
+    Examples
+    --------
+    Without a seed (non-deterministic):


The actual formatting for the example blocks need to be slightly adapted to make the documentation render correctly. I'll push a commit to take care of it. 👍

behackl · 2025-06-07T10:02:35Z

manim/utils/color/core.py

+        """
+        Returns the next color from the configured color list.


Suggested change

"""

Returns the next color from the configured color list.

"""Return the next color from the configured color list.

behackl · 2025-06-07T10:28:40Z

One additional thing I just noticed: there is a warning in the docstring of the random_color function concerning its performance -- I'm not sure there is a (still) good reason for it to be around. Perhaps it should be removed.

ishu9bansal · 2025-06-08T09:32:48Z

manim/utils/color/core.py

@@ -1508,9 +1508,101 @@ def random_color() -> ManimColor:
    ManimColor
        A random :class:`ManimColor`.
    """
-    import manim.utils.color.manim_colors as manim_colors
+    return RandomColorGenerator().next()


@behackl
While thinking about the warning that you mentioned.
Do you think it would make sense to use a singleton object here instead of initializing a new one each time?

In a scenario where random_color is called frequently across a project, repeatedly creating and discarding instances could be inefficient (though I'm not entirely sure how Python handles cleanup in this case).

Would it be better to define a static version of the method, allowing us to directly call next() on the class rather than an instance?

Open to your thoughts or suggestions. Happy to include this as part of the current PR or address it as a follow-up improvement.

uwezi · 2025-06-08T10:05:08Z

I have a comment - if I understand this issue correctly the difference would be that in the case of a static version/single object the sequence generated for all different uses of a random color in a scene. but this means that a change in one object using random colors on the scene will affect the sequence for all other objects as well... While individual sequences would mean that different uses of random colors will not affect each other.

ishu9bansal · 2025-06-08T12:25:33Z

@uwezi
The behavior will be same, i.e., using random_color() directly will lead to a sequence seeded gloabaly with the usage of random module directly; and creating an object of this class will generate own sequences in controlled way, not affecting each other.

I am just talking about the optimization that we can make for the default case internally.

Instead of creating a new instance of the same object each time, we can just use a single instance again and again. As the generator object needed for the default case will never change.

added class method

ishu9bansal · 2025-06-08T12:53:10Z

@behackl @uwezi
Added an internal method that takes care of the singleton, and removed the warning.
Please check.

add a random generator to hold the seed for random generation

bec30bb

github-project-automation bot added this to Dev Board Jun 4, 2025

github-project-automation bot moved this to 🆕 New in Dev Board Jun 4, 2025

[pre-commit.ci] auto fixes from pre-commit.com hooks

09e32f7

for more information, see https://pre-commit.ci

github-advanced-security bot found potential problems Jun 4, 2025

View reviewed changes

manim/utils/color/core.py Fixed Show fixed Hide fixed

manim/utils/color/core.py Fixed Show fixed Hide fixed

behackl reviewed Jun 4, 2025

View reviewed changes

behackl linked an issue Jun 4, 2025 that may be closed by this pull request

random_color() and random_bright_color() should have a parameter random_seed #1671

Open

add DOCSTRING for new class RandomColorGenerator

8e18ed7

ishu9bansal added 3 commits June 5, 2025 13:17

fix RandomColorGenerator doctest

15d49dc

introduce the sample colors param in RandomColorGenerator

c92a1c7

Update docstrings to include sample_colors param for RandomColorGener…

96a1196

…ator

github-advanced-security bot found potential problems Jun 5, 2025

View reviewed changes

manim/utils/color/core.py Fixed Show fixed Hide fixed

fix cyclic import issues

ec0e871

github-advanced-security bot found potential problems Jun 5, 2025

View reviewed changes

behackl reviewed Jun 7, 2025

View reviewed changes

fix indentations for code blocks

fc2c24d

docstring formatting changes

d1af775

ishu9bansal commented Jun 8, 2025

View reviewed changes

removed performance warning

95c1a9f

added class method

		"""
		A generator for producing random colors from a given list of Manim colors,

	"""
	A generator for producing random colors from a given list of Manim colors,
	"""A generator for producing random colors from a given list of Manim colors,

	sequence of `ManimColor` instances. If no seed is provided, the selection is
	sequence of :class:`.ManimColor` instances. If no seed is provided, the selection is

	If None (default), colors are chosen using the global random state.
	If ``None`` (the default), colors are chosen using the global random state.

	A custom list of Manim colors to sample from. Defaults to the full Manim color palette.
	A custom list of Manim colors to sample from. Defaults to the full Manim
	color palette.

	"""
	Returns the next color from the configured color list.
	"""Return the next color from the configured color list.

Introduce seed in random_color method to produce colors deterministically #4265

Are you sure you want to change the base?

Introduce seed in random_color method to produce colors deterministically #4265

Uh oh!

Conversation

ishu9bansal commented Jun 4, 2025

Overview: What does this pull request change?

Motivation and Explanation: Why and how do your changes improve the library?

Further Information and Comments

Reviewer Checklist

Uh oh!

ishu9bansal commented Jun 4, 2025

Uh oh!

Uh oh!

Uh oh!

behackl left a comment

Choose a reason for hiding this comment

Uh oh!

ishu9bansal commented Jun 4, 2025

Uh oh!

uwezi commented Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ishu9bansal commented Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ishu9bansal commented Jun 5, 2025

Uh oh!

Check notice

Uh oh!

behackl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

behackl commented Jun 7, 2025

Uh oh!

ishu9bansal Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

uwezi commented Jun 8, 2025

Uh oh!

ishu9bansal commented Jun 8, 2025

Uh oh!

ishu9bansal commented Jun 8, 2025

Uh oh!

Uh oh!

Introduce seed in `random_color` method to produce colors deterministically #4265

Introduce seed in `random_color` method to produce colors deterministically #4265

uwezi commented Jun 4, 2025 •

edited

Loading

ishu9bansal commented Jun 5, 2025 •

edited

Loading

ishu9bansal Jun 8, 2025 •

edited

Loading